PKI Services: Migrate to IBM HTTP Server - Powered by Apache

1. Locate the section of the conf/httpd.conffile that contains the LoadModule directives. Ensure that the following directives are specified and not commented out (a # in the first position of a line indicates that the line is a comment).
   • LoadModule rewrite_module modules/mod_rewrite.so
   • LoadModule alias_module modules/mod_alias.so
   • LoadModule authnz_saf_module modules/mod_authnz_saf.so (This LoadModule directive is located after the # z/OS specific modules comment.)
2. Locate the existing AddType directives in the conf/httpd.conf and add the AddType directives from the PKI Services sample httpd.conf file:
   • AddType application/x-x509-user-cert.cer
   • AddType application/x-x509-ca-cert.der
   • AddType application/octet-stream.msi
   • AddType application/pkix-crl.crl
3. Add the Include directives for the VirtualHost configuration files from the PKI Services sample httpd.conf file near the end of the conf/httpd.conf file:
   • Include conf/vhost80.conf
   • Include conf/vhost443.conf
   • Include conf/vhost1443.conf
   Note: If you use different port numbers than 80, 443, and 1443, change the name of the files to match the port numbers that are used. For example, if you use port 1080 instead of 80 for the unsecure port, change the vhost80.conf file to vhost1080.conf. Also, make sure that the port number change is made within the vhost*.conf files. For example, change the <VirtualHost *:80> directive to <VirtualHost *:1080>.

cp /usr/lpp/pkiserv/samples/vhost*.conf /etc/websrv/conf

1. Change all instances of <server-domain-name> to the fully qualified domain name of your web server. (This is in the Hostname directive value that is from the old httpd.conf files).
2. Change all instances of <application-root> to the pki-install-dir value. (/usr/lpp/pkiserv/ by default).
3. If you are not using the default location of /etc/pkiserv for the PKI Service configuration directory, update the SetEnv directive for _PKISERV_CONFIG_PATH with the value specified in the old httpd.conf files (as InheritEnv directives) or in the old httpd.envvars file. If additional _PKISERV_CONFIG_PATH_* environment variables are defined in your old httpd.conf or httpd.envvars files, add another SetEnv directive for each in the VirualHost configuration files.
4. The ScriptAliasMatch directives replace the Exec directives from the old httpd.conf files. The sample vhost*.conf files provide ScriptAliasMatch directives for the PKIServ and Customers domain names. Change or add additional ScriptAliasMatch directives based on the Exec directives from the old httpd.conf file. (ScriptAliasMatch directives for public-cgi URLs are placed in the vhost80.conf file, ssl-cgi-bin URLs are placed in the vhost443.conf file, and clientauth-cgi-bin URLs are placed in the vhost1443.conf file).
   Old httpd.conf file Exec directives:

   Exec /PKIServ/public-cgi/* /usr/lpp/pkiserv/PKIServ/public-cgi/*
   Exec /Customers/public-cgi/* /usr/lpp/pkiserv/PKIServ/public-cgi/*

   Equivalent vhost80.conf file ScriptAliasMatch directive:

   ScriptAliasMatch /(PKIServ|Customers)/public-cgi/(.*) /usr/lpp/pkiserv/PKIServ/public-cgi/$2

5. The AliasMatch directives replace the Pass directives from the old httpd.conf files. The sample vhost*.conf files provide AliasMatch directives for the PKIServ and Customers domain names. Change or add additional AliasMatch directives based on the Pass directives from the old httpd.conf file. (AliasMatch directives for public-cgi URLs are placed in the vhost80.conf file, ssl-cgi-bin URLs are placed in the vhost443.conf file, and clientauth-cgi-bin URLs are placed in the vhost1443.conf file).
   Old httpd.conf Pass directives:

   Pass /PKIServ/cacerts/* /var/pkiserv/*
   Pass /PKIServ/PKIXEnroll/* /usr/lpp/pkiserv/ActiveX/PKIXEnroll/*
   Pass /PKIServ/PKICEnroll/* /usr/lpp/pkiserv/ActiveX/PKICEnroll/*

   Equivalent vhost80.conf file AliasMatch directives:

   AliasMatch /PKIServ/cacerts/(.*) /var/pkiserv/$1
   AliasMatch /PKIServ/(PKIXEnroll|PKICEnroll)/(.*) /usr/lpp/pkiserv/ActiveX/$1/$2

6. The Redirect directives from the old httpd.conf files are replaced with RewriteRule directives in the vhost*.conf files. If you are not using the PKIServ and Customers domain names or have additional domain names, you will need to change or create new RewriteRule directives. Also, if you are not using ports 80 and 443, the ports you are using for the non-secure and server authentication SSL must be added to the URL in the RewriteRule directives.
   Old httpd.conf Redirect directive:

   Redirect /PKIServ/ssl-cgi/* https://pokey.example.com/PKIServ/ssl-cgi-bin/*
   Redirect /PKIServ/ssl-cgi/auth/* https://pokey.example.com/PKIServ/ssl-cgi-bin/auth/*         

   Equivalent RewriteRule directive:

   RewriteRule ^/(PKIServ|Customers)/ssl-cgi/(.*)https://pokey.example.com/$1/ssl-cgi-bin/$2 [R,NE]

   Note: This example is for redirecting from a non-secure URL to a server authentication SSL URL using the standard SSL port of 443. If a non-standard port is being used, the port number must be specified after the host name. For example, if port 4443 is used instead of 443, the URL starts with: https://pokey.example.com:4443/PKIServ/....
7. The Directory and DirectoryMatch directives replace the Protect and Protection directives from the old httpd.conf files. The sample vhost*.conf files provide Directory and DirectoryMatch directives for the PKIServ and Customers domain names. Change or add additional Directory and DirectoryMatch directives based on the Protect and Protection directives from the old httpd.conf file. The surrogate user ID specified in the Directory/DirectoryMatch directives is PKISERV. If you use a different surrogate user ID, you must change PKISERV to the user ID specified in the old httpd.conf files.
8. The LocationMatch directives in the vhost*.conf files apply specific behavior to a specific URL for the PKIServ and Customers domain names. Change or add LocationMatch directives based on the domain names in the old httpd.conf files.

1. Update the keyfile value from the value that is specified in the old httpd.conf file. (This assumes the IBM HTTP Server - Powered by Apache runs as the same USERID as the IBM HTTP Server powered by Domino.)
   Old httpd.conf keyfile directive:

   keyfile SSLring SAF    

   Equivalent keyfile directive:

   Keyfile /saf SSLring   

2. If you configured the IBM HTTP Server powered by Domino to perform revocation checking and want to continue to perform revocation checking in the IBM HTTP Server - Powered by Apache, add the following directive to the vhost1443.conf file after the SSLClientAuth directive:
   • SSLCRLHostName - Set the value from the old httpd.conf file SSLX500Host directive.
   • SSLCRLPort - Set the value from the old httpd.conf file SSLX500Port directive.
   • SSLCRLUserID - Set the value from the old httpd.conf file SSLX500UserID directive.
   • SSLStashfile - Set the value from the old httpd.conf file SSLX500Password directive.
     Note: SSLStashfile is the fully qualified path to the file that contains the password for the user name on the LDAP server. This directive is not required for an anonymous bind. Use it when you specify a user ID. Use the sslstash command, which is in the bin directory of IBM HTTP Server, to create your CRL password stash file. Specify the password that you use to log in to your LDAP server as the password on the sslstash command. The format of the sslstash command is:

     sslstash [-c] file function password

     where:

     -c

     Creates a new stash file. If not specified, an existing file is updated.

     file

     Is the fully qualified name of the file to create or update.

     function

     Indicates the function for which the password is to be used. Valid values include crl and crypto.

     password

     Is the password to stash.